.TH std::complex 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::complex \- std::complex

.SH Synopsis
   Defined in header <complex>
   template< class T >                    \fB(1)\fP
   class complex;
   template<> class complex<float>;       \fB(2)\fP (until C++23)
   template<> class complex<double>;      \fB(3)\fP (until C++23)
   template<> class complex<long double>; \fB(4)\fP (until C++23)

   Specializations of std::complex for cv-unqualified
   standard
   (until C++23) floating-point types are
   TriviallyCopyable
   (since C++23) LiteralTypes for representing and manipulating complex number.

.SH Template parameters

       the type of the real and imaginary parts. The behavior is unspecified (and may
   T - fail to compile) if T is not a cv-unqualified
       standard
       (until C++23) floating-point type and undefined if T is not NumericType.

.SH Member types

   Member type Definition
   value_type  T

.SH Member functions

   constructor   constructs a complex number
                 \fI(public member function)\fP
   operator=     assigns the contents
                 \fI(public member function)\fP
   real          accesses the real part of the complex number
                 \fI(public member function)\fP
   imag          accesses the imaginary part of the complex number
                 \fI(public member function)\fP
   operator+=
   operator-=    compound assignment of two complex numbers or a complex and a scalar
   operator*=    \fI(public member function)\fP
   operator/=

.SH Non-member functions

   operator+           applies unary operators to complex numbers
   operator-           \fI(function template)\fP
   operator+           performs complex number arithmetic on two complex values or a
   operator-           complex and a scalar
   operator*           \fI(function template)\fP
   operator/
   operator==          compares two complex numbers or a complex and a scalar
   operator!=          \fI(function template)\fP
   (removed in C++20)
   operator<<          serializes and deserializes a complex number
   operator>>          \fI(function template)\fP
   get(std::complex)   obtains a reference to real or imaginary part from a
   (C++26)             std::complex
                       \fI(function template)\fP
   real                returns the real part
                       \fI(function template)\fP
   imag                returns the imaginary part
                       \fI(function template)\fP
   abs(std::complex)   returns the magnitude of a complex number
                       \fI(function template)\fP
   arg                 returns the phase angle
                       \fI(function template)\fP
   norm                returns the squared magnitude
                       \fI(function template)\fP
   conj                returns the complex conjugate
                       \fI(function template)\fP
   proj                returns the projection onto the Riemann sphere
   \fI(C++11)\fP             \fI(function template)\fP
   polar               constructs a complex number from magnitude and phase angle
                       \fI(function template)\fP
.SH Exponential functions
   exp(std::complex)   complex base e exponential
                       \fI(function template)\fP
                       complex natural logarithm with the branch cuts along the
   log(std::complex)   negative real axis
                       \fI(function template)\fP
                       complex common logarithm with the branch cuts along the negative
   log10(std::complex) real axis
                       \fI(function template)\fP
.SH Power functions
   pow(std::complex)   complex power, one or both arguments may be a complex number
                       \fI(function template)\fP
   sqrt(std::complex)  complex square root in the range of the right half-plane
                       \fI(function template)\fP
.SH Trigonometric functions
   sin(std::complex)   computes sine of a complex number (\\({\\small\\sin{z}}\\)sin(z))
                       \fI(function template)\fP
   cos(std::complex)   computes cosine of a complex number (\\({\\small\\cos{z}}\\)cos(z))
                       \fI(function template)\fP
   tan(std::complex)   computes tangent of a complex number (\\({\\small\\tan{z}}\\)tan(z))
                       \fI(function template)\fP
   asin(std::complex)  computes arc sine of a complex number
   \fI(C++11)\fP             (\\({\\small\\arcsin{z}}\\)arcsin(z))
                       \fI(function template)\fP
   acos(std::complex)  computes arc cosine of a complex number
   \fI(C++11)\fP             (\\({\\small\\arccos{z}}\\)arccos(z))
                       \fI(function template)\fP
   atan(std::complex)  computes arc tangent of a complex number
   \fI(C++11)\fP             (\\({\\small\\arctan{z}}\\)arctan(z))
                       \fI(function template)\fP
.SH Hyperbolic functions
                       computes hyperbolic sine of a complex number
   sinh(std::complex)  (\\({\\small\\sinh{z}}\\)sinh(z))
                       \fI(function template)\fP
                       computes hyperbolic cosine of a complex number
   cosh(std::complex)  (\\({\\small\\cosh{z}}\\)cosh(z))
                       \fI(function template)\fP
                       computes hyperbolic tangent of a complex number
   tanh(std::complex)  (\\({\\small\\tanh{z}}\\)tanh(z))
                       \fI(function template)\fP
   asinh(std::complex) computes area hyperbolic sine of a complex number
   \fI(C++11)\fP             (\\({\\small\\operatorname{arsinh}{z}}\\)arsinh(z))
                       \fI(function template)\fP
   acosh(std::complex) computes area hyperbolic cosine of a complex number
   \fI(C++11)\fP             (\\({\\small\\operatorname{arcosh}{z}}\\)arcosh(z))
                       \fI(function template)\fP
   atanh(std::complex) computes area hyperbolic tangent of a complex number
   \fI(C++11)\fP             (\\({\\small\\operatorname{artanh}{z}}\\)artanh(z))
                       \fI(function template)\fP

.SH Helper types

   std::tuple_size<std::complex>    obtains the number of components of a std::complex
   (C++26)                          \fI(class template specialization)\fP
   std::tuple_element<std::complex> obtains the underlying real and imaginary number
   (C++26)                          type of a std::complex
                                    \fI(class template specialization)\fP

   Array-oriented access

   For any object z of type std::complex<T>, reinterpret_cast<T(&)[2]>(z)[0] is the
   real part of z and reinterpret_cast<T(&)[2]>(z)[1] is the imaginary part of z.

   For any pointer to an element of an array of std::complex<T> named p and any valid
   array index i, reinterpret_cast<T*>(p)[2 * i] is the real part of the complex number
   p[i], and reinterpret_cast<T*>(p)[2 * i + 1] is the imaginary part of the complex
   number p[i].

   The intent of this requirement is to preserve binary compatibility between the C++
   library complex number types and the C language complex number types (and arrays
   thereof), which have an identical object representation requirement.

.SH Implementation notes

   In order to satisfy the requirements of array-oriented access, an implementation is
   constrained to store the real and imaginary parts of a std::complex specialization
   in separate and adjacent memory locations. Possible declarations for its non-static
   data members include:

     * an array of type value_type[2], with the first element holding the real part and
       the second element holding the imaginary part (e.g. Microsoft Visual Studio);
     * a single member of type value_type _Complex (encapsulating the corresponding C
       language complex number type) (e.g. GNU libstdc++);
     * two members of type value_type, with the same member access, holding the real
       and the imaginary parts respectively (e.g. LLVM libc++).

   An implementation cannot declare additional non-static data members that would
   occupy storage disjoint from the real and imaginary parts, and must ensure that the
   class template specialization does not contain any padding bit. The implementation
   must also ensure that optimizations to array access account for the possibility that
   a pointer to value_type may be aliasing a std::complex specialization or array
   thereof.

.SH Literals

   Defined in inline namespace std::literals::complex_literals
   operator""if
   operator""i    a std::complex literal representing purely imaginary number
   operator""il   \fI(function)\fP
   \fI(C++14)\fP

.SH Notes

       Feature-test macro       Value    Std                   Feature
                               201711L (C++20) Constexpr simple complex mathematical
   __cpp_lib_constexpr_complex                 functions in <complex>
                               202306L (C++26) More constexpr for <complex>

.SH Example


// Run this code

 #include <cmath>
 #include <complex>
 #include <iomanip>
 #include <iostream>

 int main()
 {
     using namespace std::complex_literals;
     std::cout << std::fixed << std::setprecision(1);

     std::complex<double> z1 = 1i * 1i; // imaginary unit squared
     std::cout << "i * i = " << z1 << '\\n';

     std::complex<double> z2 = std::pow(1i, 2); // imaginary unit squared
     std::cout << "pow(i, 2) = " << z2 << '\\n';

     const double PI = std::acos(-1); // or std::numbers::pi in C++20
     std::complex<double> z3 = std::exp(1i * PI); // Euler's formula
     std::cout << "exp(i * pi) = " << z3 << '\\n';

     std::complex<double> z4 = 1.0 + 2i, z5 = 1.0 - 2i; // conjugates
     std::cout << "(1 + 2i) * (1 - 2i) = " << z4 * z5 << '\\n';
 }

.SH Output:

 i * i = (-1.0,0.0)
 pow(i, 2) = (-1.0,0.0)
 exp(i * pi) = (-1.0,0.0)
 (1 + 2i) * (1 - 2i) = (5.0,0.0)

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to              Behavior as published              Correct behavior
   LWG 387 C++98      std::complex was not guaranteed to be           guaranteed to be
                      compatible with C complex                       compatible

.SH See also

   C documentation for
   Complex number arithmetic
